home *** CD-ROM | disk | FTP | other *** search
- BOI Developer Reference Manual 2.00 12/15/92
-
- BBS Onliner Interface 2.00 (Pascal)
- (C) 1992 Andrew J. Mead
- All Rights Reserved.
-
- Contact:
- POB 1155
- Chapel Hill, NC 27514-1155
- or
- 1:3641/417 FidoNet 75:7919/417 DoorNet
- #1@9952 WWIVnet #1@9395 VirtualNet
-
- Turbo Pascal and TP are registered trademarks of Borland International.
- Borland Pascal and BP are registered trademarks of Borland International.
-
- Sections in order of Appearance
- 1 Initial Statement
- 2 ShareWare Liscense Agreement
- 3 Registration Cost
- 4 Technical Support
- 5 Style Conventions
-
- 6 How to write an Onliner (overview)
- 7 Substitutions
-
- 8 Global Constants
- 9 Global Types
- 10 Global Static Variables (Typed Constants)
- 11 Global Variables
- 12 Unit Explanations
-
- 13 Features
- 14 Future Enhancements
- 15 Message Bases
-
- 1) Initial Statement.
- Thanks to Kent Ogle, John Reid, Mike Robinson, Joe Dabrowski, and
- Jochen Ott. The BOI 2.00 is the result of 8 months of intense
- programming effort. I release the BOI 1.20 to the public two
- years ago fully intending to continue developement. Two factors
- conspired against me. The first was my getting a 40-50 hour/week
- programming job. The second was lack of registrations and support
- from the general public. I tend to blame the second on myself. I
- was new to Shareware, and I misunderstood the market. I was
- arguably the worst technical writer ever to hit the streets. I
- still look back on the BOI 1.20 very proudly. I consider it a
- fine piece of work. It took me only three months to write the
- entire thing. I had owned a modem less than a year at that point.
-
- Times have changed, and I've learned how to write documentation.
- Earlier this year (1992), I finally was able to free up enough
- time to look back on the BOI. For my own releases, I was up to
- BOI 1.23 which only contained a couple minor changes from the BOI
- 1.20. For those of you familiar with the BOI 1.20, this release
- may come as a complete surprise. There are nearly 1000 more lines
- of source code, and the code that remains has been greatly
- rewritten. I've also renamed all of the standard variables.
-
- Thanks for taking the time to look at my product. I hope you like
- it. I can be reached at the addresses found throughout the
- documentation. Don't hesitate to contact me.
-
-
- 2) Shareware License Agreement
- This package is ShareWare. If you use this package, you are
- required to register it. If you merely use this package as a
- learning tool, and you do not use any portions of it in your own
- programming, you are not obligated to register.
-
- If you write any software that uses the BBS Onliner Interface,
- your opening copyright screen must include this after your own
- copyright messages.
-
- BBS Onliner Interface version 2.00
- (C) 1992 Andrew J. Mead
- All Rights Reserved.
- Contact: POB 1155 Chapel Hill, NC 27514-1155
-
- If you only use parts of the BOI, you can use this instead.
-
- portions (C) 1992 Andrew J. Mead (BOI 2.00)
- All Rights Reserved.
- Contact: POB 1155 Chapel Hill, NC 27514-1155
-
- If you alter the code, put your revision number AFTER the '2.00'
- ie (version 2.00 rev 1a). I will maintain, and steadily
- update the interface. If you have any ideas, suggestions, or
- improvements, please send them to me. There is plenty of room for
- enhancement, addition, and improvement in the interface.
-
-
- 3) Registration Costs
- Here is a basic chart of costs ($US):
- Standard Professional Standard+Pro Upgrade
- North Carolina - $31.80 $53.00 $63.60
- USA & Canada - $30.00 $50.00 $60.00
- Other Countries - $33.00 $53.00 $66.00
- This chart reflects registration fees, processing costs, and
- taxes. It does not include your postage to me, or any of your
- currency conversion costs.
-
- Registration Options:
- Standard Registration ($US25+fees)
- Standard Registration gives you license to use the BOI or
- portions thereof in any Shareware or Freeware software that you
- may write. Registration will not expire, and you are entitled
- to use any future public (non-beta) MS-DOS releases as well.
-
- Professional Registration ($45US+fees)
- Professional Upgrade from Standard Registration ($25US+fees)
- Professional Registration gives you all the rights of the
- Standard Registration. I also will make available to you (via
- download from my BBS, or via Fido FREQ) current BOI betas. I
- will also send you the current source code (you must sign the
- non-disclosure agreement contained in the registration form) to
- my online game Madness. You will also will have the option of
- carrying the Fido Technology message area BOI-BETA.
-
- Commercial Registration and License
- If you intend to write commercial software with the BBS Onliner
- Interface, or portions thereof, you will need to contact me
- personally to negotiate an appropriate license agreement.
-
- Note: All new registrations of the BOI 1.20 ($35US) received after
- December 15th, 1992 will be treated as Standard Registrations.
- Those received before June 30th, 1993 will be offered a $10US
- credit towards upgrading to the Professional Registration that
- is good until December 15, 1993.
-
- Processing Fees
- Canada and United States : $5.00
- Others : $8.00
- The processing fee is used to cover my diskette, postage, and
- phone costs associated with staying in contact with registered
- users.
-
-
- 4) Technical Support
- I am always willing to offer support. I can be reached on my BBS.
-
- Infinite Improbability BBS - Private Idaho BBS - The Old Same Place
- +919-489-9446 (v32b)
- 1:3641/417 FidoNet @9395 VirtualNet
- @9952 WWIVnet 75:7919/417 DoorNet
-
- Programming support can also be found in the message area BOI-PROG
- BOI-PROG is currently in private distribution among FidoNet
- systems. If enough interest warrants, I will attempt to backbone
- this echo. I can also be reached via postal mail, be sure to
- include a self addressed stamped envelope to guarantee reply.
-
- I am always looking for people to help with technical support.
-
-
- 5) Style Conventions.
- This document, and my other documentation files, are 72 characters
- wide. The document can be shifted to the right when printing to
- allow for ring binder holes to be punched without text wrapping
- around. There are no imbeded form feeds.
-
- My programming style is:
-
- - Capitalize procedure and function calls [WriteLn('sample')]
- - Fully capitalize procedural declarations [Procedure DOTHIS;]
- - Four space basic indentation scheme with matching begin..end
- pairs offset two spaces.
- - Nested procedures indented two spaces
- - repeat..until code blocks include begin..end pair
- - Const, Type, and Var are only capitalized for global blocks
- - Blank statements supressed (remove unnecessary semi-colons)
- - Procedural blocks are commented with all nested calls.
- Functions are preceded with "f"
- Interrupts are preceded with "i"
- Objects are preceded with "o"
- Program blocks are preceded with "p"
- Unit blocks are preceded with "u"
-
- Function TESTVAL : word;
- Procedure INCCOUNTERS(cnta, cntb : longint);
- begin {* fTestVal,IncCounters *}
- end; {* fTestVal,IncCounters *}
-
-
- 6) How To Write an Onliner
- The BBS Onliner Interface comes with a working online game (HiLo)
- that you can compile and run! HiLo follows the same structure,
- and uses much of the same code as most of my online games. By
- examining HiLo, or modifying it into another game, you can see
- how simple programming with the BOI can be. By using the BOI,
- you, the programmer, need not be concerned with anything other
- than writing the game or utility. The BOI handles communications,
- the interface to the BBS, and video output.
-
- To write an onliner, you'll need to include several units into
- your Unit clause, put the proper values in DOORLIB.DAT, and
- substitute certain BOI procedures, functions, and variables for
- the ones you are currently using (see next section.)
-
- The following is a working shell of an online game.
-
- Program Onliner;
-
- Uses
- DOS,
- CRT,
- KEY,
- BOIDECL,
- DOORLIB,
- GETCMBBS,
- IOLIB,
- SUPPORT;
-
- Procedure PLAYGAME;
- begin {* PlayGame *}
- { This is the main program block for your game }
- end; {* PlayGame *}
-
- begin {* pOnliner *}
- if boi_allowavt then QueryUser(['Q','1'..'4')
- else QueryUser(['Q','1','2']);
- WriteCopy(false);
- repeat
- begin
- PlayGame
- EndGame('Players',playerpoints > 0,bois_points,
- bois_highscore)
- end
- until not boi_replay
- end. {* pOnliner *}
-
- DOORLIB.DAT
- You will need to create a copy of this include file for each of
- the doors you write. This is the information that needs to be
- supplied: (Sample data from HiLo's DOORLIB.DAT)
-
- 'HILOINFO.DOC', (* HiLo documentation filename *)
- This is show to the user when GetCmBBS.GetCommand
- encounters a fatal initialization condition.
- 'HILOHOF.TXT', (* HiLo text Hall of Fame filename *)
- This is used by Support.EndGame.
- 'HILOHOF.DAT', (* HiLo data Hall of Fame filename *)
- This is used by Support.EndGame.
- 'BOI.LOG', (* activity / error log filename *)
- This can be overridden by use of environment variables.
- 'HiLo', (* game name *)
- '2.00'); (* game version number *)
-
- dl_progset : set of char = [#00];
- (* valid additional command line switches *)
-
- 7) Substitutions
- This is a quick list of Turbo Pascal Procedures, Functions, and
- variables that should not be used in your online door. Where
- applicable, the equivalent BOI procedure or variable is given.
- Remember, this is only a guide. Most of these procedures are
- to be avoided because they don't affect the remote screen, and
- they don't update certain BOI variables (i.e. boi_l_textattr).
-
- --Sample
- TurboFunction BOIFunction necessity
- Additional notes on what is going here
-
- --Procedures and Functions
- System.Append IOLib.OpenText recommended
- Crt.AssignCrt -none-
- This procedure should not be called
- Crt.ClrEOL IOLib.ClrPortEOL required
- Crt.ClrScr IOLib.ClrPortScr required
- Crt.DelLine -none-
- This procedure should not be called
- Crt.GotoXY IOLib.GotoPortXY required
- Crt.HighVideo -none-
- Crt.InsLine -none-
- This procedure should not be called
- Crt.KeyPressed IOLib.PortKeyPressed required
- Crt.LowVideo -none-
- Crt.NormVideo -none-
- Crt.NoSound -none-
- System.Read (file) System.BlockRead recommended
- Crt.ReadKey IOLib.ReadPortKey required
- System.ReadLn IOLib.GetString required
- System.Reset (file) IOLib.OpenFile recommended
- System.Reset (text) IOLib.OpenText recommended
- System.Rewrite (file) IOLib.OpenFile recommended
- System.Rewrite (text) IOLib.OpenText recommended
- Crt.Sound -none-
- Crt.TextBackground IOLib.PortBackground required
- Crt.TextColor IOLib.PortColor required
- Crt.TextColor IOLib.TextPortColor required
- Crt.TextMode -none-
- This procedure should not be called
- Crt.WhereX -none-
- Crt.WhereY -none-
- Extreme caution should be used with these two functions.
- You should consider IOLib.SetPortXY and IOLib.ResetPortXY.
- Crt.Window IOLib.PortWindow required
- System.Write (video) IOLib.SendString(,false) required
- System.WriteLn (video) IOLib.SendString(,true) required
- For formatting output, you should use IOLib.IntStr,
- IOLib.RealStr, and IOLib.PadStr.
- System.Write (file) System.BlockWrite recommended
-
- --System variables
- crt.directvideo IOLib.SetLocalGraphMode
- This variable should be left alone
- crt.textattr boi_l_textattr required
- Do not manually change boi_l_textattr. The procedure
- IOLib.ChangeColor should be used instead. The variable
- boi_r_textattr tracks the remote text attribute.
- crt.windmin -none-
- crt.windmax -none-
- These variables should not be used
-
- 8) Global Constants
- BOIDECL
- boi_version = '2.00'
- Current BBS Onliner Interface version number. This should
- only be changed with permission.
-
- read_only = $00 (open file for reading)
- writeonly = $01 (open file for writing)
- readwrite = $02 (open file for reading and/or writing)
- File access modes.
-
- denyall = $10 (deny all file access to others)
- denywrite = $20 (deny write to file access to others)
- denyread = $30 (deny read from file access to others)
- denynone = $40 (allow others to read and/or write to file)
- File sharing (DOS Share) modes. These are used by OpenFile
- and OpenText. When calling either of those procedures you
- should add one access mode to one sharing mode:
- OpenFile(...,read_only + denynone,...);
-
- SUPPORT
- bois_highscore = true
- bois_lowscore = false
- bois_cash = true
- bois_points = false
- These are declared only to help increase the readability of
- calling Procedure Support.EndGame.
-
- 9) Global Types
- BOIDECL
- ptrmask
- This is used to allow easy access to a pointer's segment and
- offset. This is used for absolute casting:
- var
- tempptr : pointer;
- tempmsk : ptrmask absolute tempptr;
-
- facctype (file access modes)
- tasktype (Operating Systems/Environments)
- boi_grmode (video character graphics modes)
- boi_commode (remote communications modes)
- boi_statmodes (remote user status line modes)
- boi_dropmode (BBS drop file modes)
- These simple enumerated types are used by the BOI to keep
- track of its enviroment.
-
- stdproc
- This is declared for basic procedural variables.
-
- 10) Global Static Variables (Typed Constants)
- BOIDECL
- -setup
- boi_local = true (local mode (no remote))
- boi_echo = false (echo remote play on local console)
- boi_quiet = false (supress output of bell (^G) to local
- console)
- boi_replay = false (allow user to play multiple games)
- boi_statmode = sm_time (what to display on user status line)
- dos_share = true (DOS Share is loaded)
- boi_hoflim = 20 (how many scores in HOF user can have)
-
- -time
- boi_timeover = false (time has expired)
- boi_againtime = 10 (mins) (minimum time for boi_replay checking)
- boi_warntime = 5 (mins) (warn user about time remaining limit)
-
- the following are updated 18.2 times per second by the BOI's
- timer interrupt.
- boi_ticks = $17fe80 (this initial value (24 hrs) is
- re-initialized by GetCmBBS. When it
- reaches zero (0), time has expired)
- boi_stall = 0 (this counter increments. It is used
- by ReadPortKey to detect user
- inactivity)
- boi_timer = 0 (this counter increments. It is the
- opposite of boi_ticks. It shows
- just how long the game has been
- active. This should be used instead
- of any calls to MemL[$40:$0C])
- boi_stime = 0 (this variable holds the last timer
- tick at which IOLib.UpdateStatLine
- was called)
-
- -communications
- boi_checkcd = true (carrier drop can be detected)
- boi_cdlost = false (carrier has been lost during play)
- boi_portnum = 0 (0==COM1, 1==COM2, etc...)
- boi_cmode = com_none (internal BOI flag)
- boi_str = ' No Comm' (displayed on User Status Line)
- foss_init = $00 (bit flags detailing if and how
- FOSSIL can be used. See source
- code (GetCmBBS) for details)
-
- The following are used by the BOI's internal comm routines.
- If local play or FOSSIL routines are used, these are ignored.
- boi_ctsrts = false (CTS/RTS handshaking is being used by
- internal comm routines)
- boi_portadd = $03F8 (base port address for communications)
- boi_portint = $0C (Interrupt used by IRQ)
- boi_picmask = $EF (enabling mask for Programmable
- Interrupt Controller (IRQ0..IRQ7))
- boi_pic2msk = $00 (enabling mask for second or cascade
- PIC (IRQ8..IRQ15))
- boi_cascade = false (IRQ in use is on cascade PIC)
- boi_portstatus = false (internal Async routines active)
-
- -video
- boi_r_color = false (remote wants color/monochrome)
- boi_l_color = false (local wants color/monochrome)
- boi_allowavt = false (AVATAR/1 graphics are allowed)
- boi_ansiarr (ANSI codes mapped over color values)
- boi_r_grmode = gr_ansi (remote graphics mode)
- boi_l_grmode = gr_tpcrt (local graphics mode)
-
- -miscellaneous
- boi_plusidx = 0 (These variables are used by GetCmBBS
- boi_minusidx = 0 to let the program know that it needs
- boi_equalidx = 0 to perform additional command line
- boi_closeidx = 0 processing for door specific command
- boi_openidx = 0 line arguments. Pass the value to
- boi_dotidx = 0 ParamStr())
- boi_dmode = dfnone (drop file that was processed)
- boi_nextchar = #$00 (used to feed a character to GetString
-
- KEY
- key_regnum = 'N/A' (Registration number)
- key_regstr = 'Unregistered Version'
- (name of BBS that has registered)
- key_registered = false (game has been registered)
- key_regname = 'Your SysOp'
- (name of registrant)
-
- 11) Global Variables
- BOIDECL
- -setup
- boi_gamepath (path/filespec to current executable
- "C:\BBS\GAME\HILO.EXE")
- boi_gamedir (path to current excecutable "C:\BBS\GAME\")
- boi_gamename (current game file "HILO")
- boi_gameext (current executable extension ".EXE"
- boi_tasker (current operating system/environment)
- boi_tvers (operating system version number)
- boi_tstr (string description of current operating system)
- boi_tintr (basic interrupt to operating systems functions)
- in_dos (in_dos flag pointer)
- BOI_Wait (procedure to be called when giving up timeslice)
- BOI_Crit (procedure to call when beginning critical task)
- BOI_Safe (procedure to call when ending critical task)
-
- -time
- boi_starttime (starting time (hr,min,sec) of game)
- boi_startdate (starting date (yr,month,day) of game)
- boi_usetime (game is a timed game)
- boi_gametime (old variable indicating time in minutes, unused)
- boi_ticksleft (timer ticks left to play (1092 per minute))
- boi_timexp (time has expired indicator)
-
- -video
- boi_pagelength (size of remote player's screen in lines)
-
- -player
- boi_username (player's alias/real name)
- boi_usename (boi_username is valid)
- boi_realname (player's real name if boi_username is alias)
- boi_usereal (boi_realname is valid)
-
- -miscellaneous
- boi_texthof (pathfilespec for text Hall of Fame)
-
- SUPPORT
- playerpoints (playerscore variable)
-
-
- 12) Unit Explanations
- BOIDECL
- This unit is the basic foundation upon which the other units are
- built. This is where the vast majority of global variables and
- values are defined and initialized. The initialization code for
- this unit installs the BOI's timer interrupt and checks to see
- if the door is running under a multitasker.
-
- KEY
- This is just a shell. You'll have to write your own routines
- for this one.
-
- DOORLIB
- This unit provides basic information to the BOI about your door.
- You need to maintain a seperate DOORLIB.DAT file for each of
- your doors, and make sure that this unit is rebuilt upon
- compilation.
-
- GETCMBBS
- This self-initializing unit processes the command line, and
- then initializes most of the system variables and calls the
- routines to start remote communications.
- This unit is the most replaceable. If you wish to write BBS
- specific doors, you merely need to insert your own command line
- processing routines. With your own routines, you can get any
- additional dropfile information your door may require.
-
- ASYNC
- This unit contains the BOI's internal Async routines and its
- FOSSIL routines. I recommend that you do NOT include this unit
- in your program's Uses clause. It functions best when left
- undisturbed. If you must access it, you should use the various
- hooks available through the unit Support.
-
- This unit does not initialize itself (GetCmBBS gets the ball
- rolling with a call to IOLib.SetPort). It does, however, clean
- up after itself. The BOI is very fault tolerant.
-
- IOLIB
- This is where it's at. This unit contains all of the video,
- input, output, and file routines.
-
- IOSUPP
- This unit merely exists as a hook off of IOLib.ReadPortKey. It
- is used to decipher function key presses on the local keyboard.
-
- SUPPORT
- This is a collection of additional routines that you may or may
- not wish to use. It contains a Copyright screen, Hall of Fame
- routines, and a text file displayer.
-
- 13) Features
- o Distributed as Source Code
- o FOSSIL driver support
- o Internal Asynchronious routines
- o non-standard IRQ/port address communications supported
- o IRQs on second PIC supported (IRQ8..IRQ15)
- o ANSI graphics support
- o AVATAR/1 graphics support
- o highly optimized video routines - redundant calls stripped
- o local BIOS video and direct video modes
- o local/remote video modes are seperately configureable
- o multiple user status line display options
- o file sharing/locking supported
- o DESQview aware
- o Windows aware
- o OS/2 DOSbox aware
- o gives up time to multi-taskers
- o reads 18 different drop file formats
- o runs directly under virtually all MS-DOS BBS software
- o will compile as-is under TP5, TP55, TP60, and TP7
-
- 14) Future Enhancements
- Coming Soon: (on the drawing board, code fragments exists)
- o GT Power support (ran out of time to include in this release)
- o activity logging
- o enhanced error trapping and logging
- o natural language file support
- o config file script language
- o record locking/sharing
- o additional graphics modes (YALEbbs, etc...)
- o switch to Turbo Pascal 7.0 baseline
-
- Longer Range: (just some things I'm considering)
- o object orientation
- o comm routines for multiport boards (APIs needed)
- o write language file compiler/decompiler
- o ANSI sound or similiar
- o use BP7 .DLLs for multinode engine
- o take advantage of other new TP7 and BP7 features
- o add transfer protocol engine (Xmodem, Zmodem)
- o OS/2 version (compiler availability, additional registration)
- o WinNT version (compiler availability, additional registration)
-
- 15) Message Bases
- If interest warrants, I am willing to contribute to support echos
- in any of the more common hobby networks. I am personally in
- FidoNet, WWIVnet, DoorNet, and VirtualNet. I have access to
- RIME and GT PowerNet. I can get access to USEnet and Internet.
-
- I have the following areas available from my BBS. These are Fido
- Technology Network (FTN) compatible message areas. If interest
- warrants, I will attempt to get the first two areas backboned in
- Zone 1 (North America).
-
- BOI-GAMES
- This is for discussion of any doors written with the BBS Onliner
- Interface. This is intended for users and SysOps to communicate
- with eachother and door authors.
-
- BOI-PROG
- This is for discussion of the latest public release version of
- the BBS Onliner Interface. Code fragments, ideas, and
- suggestions are welcome. I am willing to answer questions, but
- I will not comment on any beta features.
-
- BOI-BETA
- This echo is restricted. It is only available to those who have
- paid for a Professional Registration. This echo will be a
- clearing house for ideas and discussion of beta versions of the
- BBS Onliner Interface.
-
- END BOI Developer Reference Manual